rochars / wavefile

 * Copyright (c) 2017-2018 Rafael da Silva Rocha.

 *

 * Permission is hereby granted, free of charge, to any person obtaining

 * a copy of this software and associated documentation files (the

 * "Software"), to deal in the Software without restriction, including

 * without limitation the rights to use, copy, modify, merge, publish,

 * distribute, sublicense, and/or sell copies of the Software, and to

 * permit persons to whom the Software is furnished to do so, subject to

 * the following conditions:

 *

 * The above copyright notice and this permission notice shall be

 * included in all copies or substantial portions of the Software.

 *

 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE

 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION

 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

 *

 */

/**

 * @fileoverview The WaveFile class.

 * @see https://github.com/rochars/wavefile

 */

/** @module wavefile */

import bitDepthLib from './vendor/bitdepth.js';

import * as imaadpcm from './vendor/imaadpcm.js';

import * as alawmulaw from './vendor/alawmulaw.js';

import {encode, decode} from './vendor/base64-arraybuffer-es6.js';

import {unpackArray, packArrayTo, unpackArrayTo} from './vendor/byte-data.js';

import makeWavHeader from './lib/make-wav-header.js';

import validateWavHeader from './lib/validate-wav-header';

import {riffChunks, findChunk_} from './vendor/riff-chunks.js';

import BufferIO from './lib/bufferio.js';

import writeWavBuffer from './lib/wav-buffer-writer.js';

import readWavBuffer from './lib/wav-buffer-reader.js';

import WavBuffer from './lib/wav-buffer.js';

/**

 * Class representing a wav file.

 * @extends WavBuffer

 * @ignore

 */

export default class WaveFile extends WavBuffer {

  /**

   * @param {?Uint8Array} bytes A wave file buffer.

   * @throws {Error} If no 'RIFF' chunk is found.

   * @throws {Error} If no 'fmt ' chunk is found.

   * @throws {Error} If no 'data' chunk is found.

   */

  constructor(bytes=null) {

    super();

    /**

     * The bit depth code according to the samples.

     * @type {string}

     */

    this.bitDepth = '0';

    /**

     * @type {!Object}

     * @private

     */

    this.dataType = {};

    this.io = new BufferIO();

    // Load a file from the buffer if one was passed

    // when creating the object

    if (bytes) {

      this.fromBuffer(bytes);

    }

  }

  /**

   * Set up the WaveFile object based on the arguments passed.

   * @param {number} numChannels The number of channels

   *    (Integer numbers: 1 for mono, 2 stereo and so on).

   * @param {number} sampleRate The sample rate.

   *    Integer numbers like 8000, 44100, 48000, 96000, 192000.

   * @param {string} bitDepthCode The audio bit depth code.

   *    One of '4', '8', '8a', '8m', '16', '24', '32', '32f', '64'

   *    or any value between '8' and '32' (like '12').

   * @param {!Array<number>|!Array<!Array<number>>|!ArrayBufferView} samples

   *    The samples. Must be in the correct range according to the bit depth.

   * @param {?Object} options Optional. Used to force the container

   *    as RIFX with {'container': 'RIFX'}

   * @throws {Error} If any argument does not meet the criteria.

   */

  fromScratch(numChannels, sampleRate, bitDepthCode, samples, options={}) {

    if (!options.container) {

      options.container = 'RIFF';

    }

    this.container = options.container;

    this.bitDepth = bitDepthCode;

    samples = this.interleave_(samples);

    this.updateDataType_();

    /** @type {number} */

    let numBytes = this.dataType.bits / 8;

    this.data.samples = new Uint8Array(samples.length * numBytes);

    packArrayTo(samples, this.dataType, this.data.samples);

    /** @type {!Object} */

    let header = makeWavHeader(

      bitDepthCode, numChannels, sampleRate,

      numBytes, this.data.samples.length, options);

    this.clearHeader_();

    this.chunkSize = header.chunkSize;

    this.format = header.format;

    this.fmt = header.fmt;

    if (header.fact) {

      this.fact = header.fact;

    }

    this.data.chunkId = 'data';

    this.data.chunkSize = this.data.samples.length;

    validateWavHeader(this);

  }

  /**

   * Set up the WaveFile object from a byte buffer.

   * @param {!Uint8Array} bytes The buffer.

   * @param {boolean=} samples True if the samples should be loaded.

   * @throws {Error} If container is not RIFF, RIFX or RF64.

   * @throws {Error} If no 'fmt ' chunk is found.

   * @throws {Error} If no 'data' chunk is found.

   */

  fromBuffer(bytes, samples=true) {

    this.clearHeader_();

    readWavBuffer(bytes, samples, this);

    this.bitDepthFromFmt_();

    this.updateDataType_();

  }

  /**

   * Return a byte buffer representig the WaveFile object as a .wav file.

   * The return value of this method can be written straight to disk.

   * @return {!Uint8Array} A .wav file.

   * @throws {Error} If any property of the object appears invalid.

   */

  toBuffer() {

    validateWavHeader(this);

    return writeWavBuffer(this);

  }

  /**

   * Use a .wav file encoded as a base64 string to load the WaveFile object.

   * @param {string} base64String A .wav file as a base64 string.

   * @throws {Error} If any property of the object appears invalid.

   */

  fromBase64(base64String) {

    this.fromBuffer(new Uint8Array(decode(base64String)));

  }

  /**

   * Return a base64 string representig the WaveFile object as a .wav file.

   * @return {string} A .wav file as a base64 string.

   * @throws {Error} If any property of the object appears invalid.

   */

  toBase64() {

    /** @type {!Uint8Array} */

    let buffer = this.toBuffer();

    return encode(buffer, 0, buffer.length);

  }

  /**

   * Return a DataURI string representig the WaveFile object as a .wav file.

   * The return of this method can be used to load the audio in browsers.

   * @return {string} A .wav file as a DataURI.

   * @throws {Error} If any property of the object appears invalid.

   */

  toDataURI() {

    return 'data:audio/wav;base64,' + this.toBase64();

  }

  /**

   * Use a .wav file encoded as a DataURI to load the WaveFile object.

   * @param {string} dataURI A .wav file as DataURI.

   * @throws {Error} If any property of the object appears invalid.

   */

  fromDataURI(dataURI) {

    this.fromBase64(dataURI.replace('data:audio/wav;base64,', ''));

  }

  /**

   * Force a file as RIFF.

   */

  toRIFF() {

    this.fromScratch(

      this.fmt.numChannels,

      this.fmt.sampleRate,

      this.bitDepth,

      unpackArray(this.data.samples, this.dataType));

  }

  /**

   * Force a file as RIFX.

   */

  toRIFX() {

    this.fromScratch(

      this.fmt.numChannels,

      this.fmt.sampleRate,

      this.bitDepth,

      unpackArray(this.data.samples, this.dataType),

      {container: 'RIFX'});

  }

  /**

   * Change the bit depth of the samples.

   * @param {string} newBitDepth The new bit depth of the samples.

   *    One of '8' ... '32' (integers), '32f' or '64' (floats)

   * @param {boolean} changeResolution A boolean indicating if the

   *    resolution of samples should be actually changed or not.

   * @throws {Error} If the bit depth is not valid.

   */

  toBitDepth(newBitDepth, changeResolution=true) {

    /** @type {string} */

    let toBitDepth = newBitDepth;

    /** @type {string} */

    let thisBitDepth = this.bitDepth;

    if (!changeResolution) {

      if (newBitDepth != '32f') {

        toBitDepth = this.dataType.bits.toString();

      }

      thisBitDepth = this.dataType.bits;

    }

    this.assureUncompressed_();

    /** @type {number} */

    let sampleCount = this.data.samples.length / (this.dataType.bits / 8);

    /** @type {!Float64Array} */

    let typedSamplesInput = new Float64Array(sampleCount + 1);

    /** @type {!Float64Array} */

    let typedSamplesOutput = new Float64Array(sampleCount + 1);

    unpackArrayTo(this.data.samples, this.dataType, typedSamplesInput);

    bitDepthLib(

      typedSamplesInput, thisBitDepth, toBitDepth, typedSamplesOutput);

    this.fromScratch(

      this.fmt.numChannels,

      this.fmt.sampleRate,

      newBitDepth,

      typedSamplesOutput,

      {container: this.correctContainer_()});

  }

  /**

   * Encode a 16-bit wave file as 4-bit IMA ADPCM.

   * @throws {Error} If sample rate is not 8000.

   * @throws {Error} If number of channels is not 1.

   */

  toIMAADPCM() {

    if (this.fmt.sampleRate !== 8000) {

      throw new Error(

        'Only 8000 Hz files can be compressed as IMA-ADPCM.');

    } else if (this.fmt.numChannels !== 1) {

      throw new Error(

        'Only mono files can be compressed as IMA-ADPCM.');

    } else {

      this.assure16Bit_();

      let output = new Int16Array(this.data.samples.length / 2);

      unpackArrayTo(this.data.samples, this.dataType, output);

      this.fromScratch(

        this.fmt.numChannels,

        this.fmt.sampleRate,

        '4',

        imaadpcm.encode(output),

        {container: this.correctContainer_()});

    }

  }

  /**

   * Decode a 4-bit IMA ADPCM wave file as a 16-bit wave file.

   * @param {string} bitDepthCode The new bit depth of the samples.

   *    One of '8' ... '32' (integers), '32f' or '64' (floats).

   *    Optional. Default is 16.

   */

  fromIMAADPCM(bitDepthCode='16') {

    this.fromScratch(

      this.fmt.numChannels,

      this.fmt.sampleRate,

      '16',

      imaadpcm.decode(this.data.samples, this.fmt.blockAlign),

      {container: this.correctContainer_()});

    if (bitDepthCode != '16') {

      this.toBitDepth(bitDepthCode);

    }

  }

  /**

   * Encode a 16-bit wave file as 8-bit A-Law.

   */

  toALaw() {

    this.assure16Bit_();

    let output = new Int16Array(this.data.samples.length / 2);

    unpackArrayTo(this.data.samples, this.dataType, output);

    this.fromScratch(

      this.fmt.numChannels,

      this.fmt.sampleRate,

      '8a',

      alawmulaw.alaw.encode(output),

      {container: this.correctContainer_()});

  }

  /**

   * Decode a 8-bit A-Law wave file into a 16-bit wave file.

   * @param {string} bitDepthCode The new bit depth of the samples.

   *    One of '8' ... '32' (integers), '32f' or '64' (floats).

   *    Optional. Default is 16.

   */

  fromALaw(bitDepthCode='16') {

    this.fromScratch(

      this.fmt.numChannels,

      this.fmt.sampleRate,

      '16',

      alawmulaw.alaw.decode(this.data.samples),

      {container: this.correctContainer_()});

    if (bitDepthCode != '16') {

      this.toBitDepth(bitDepthCode);

    }

  }

  /**

   * Encode 16-bit wave file as 8-bit mu-Law.

   */

  toMuLaw() {

    this.assure16Bit_();

    let output = new Int16Array(this.data.samples.length / 2);

    unpackArrayTo(this.data.samples, this.dataType, output);

    this.fromScratch(

      this.fmt.numChannels,

      this.fmt.sampleRate,

      '8m',

      alawmulaw.mulaw.encode(output),

      {container: this.correctContainer_()});

  }

  /**

   * Decode a 8-bit mu-Law wave file into a 16-bit wave file.

   * @param {string} bitDepthCode The new bit depth of the samples.

   *    One of '8' ... '32' (integers), '32f' or '64' (floats).

   *    Optional. Default is 16.

   */

  fromMuLaw(bitDepthCode='16') {

    this.fromScratch(

      this.fmt.numChannels,

      this.fmt.sampleRate,

      '16',

      alawmulaw.mulaw.decode(this.data.samples),

      {container: this.correctContainer_()});

    if (bitDepthCode != '16') {

      this.toBitDepth(bitDepthCode);

    }

  }

  /**

   * Write a RIFF tag in the INFO chunk. If the tag do not exist,

   * then it is created. It if exists, it is overwritten.

   * @param {string} tag The tag name.

   * @param {string} value The tag value.

   * @throws {Error} If the tag name is not valid.

   */

  setTag(tag, value) {

    tag = this.fixTagName_(tag);

    /** @type {!Object} */

    let index = this.getTagIndex_(tag);

    if (index.TAG !== null) {

      this.LIST[index.LIST].subChunks[index.TAG].chunkSize =

        value.length + 1;

      this.LIST[index.LIST].subChunks[index.TAG].value = value;

    } else if (index.LIST !== null) {

      this.LIST[index.LIST].subChunks.push({

        chunkId: tag,

        chunkSize: value.length + 1,

        value: value});

    } else {

      this.LIST.push({

        chunkId: 'LIST',

        chunkSize: 8 + value.length + 1,

        format: 'INFO',

        subChunks: []});

      this.LIST[this.LIST.length - 1].subChunks.push({

        chunkId: tag,

        chunkSize: value.length + 1,

        value: value});

    }

  }

  /**

   * Return the value of a RIFF tag in the INFO chunk.

   * @param {string} tag The tag name.

   * @return {?string} The value if the tag is found, null otherwise.

   */

  getTag(tag) {

    /** @type {!Object} */

    let index = this.getTagIndex_(tag);

    if (index.TAG !== null) {

      return this.LIST[index.LIST].subChunks[index.TAG].value;

    }

    return null;

  }

  /**

   * Return a Object<tag, value> with the RIFF tags in the file.

   * @return {!Object<string, string>} The file tags.

   */

  listTags() {

    /** @type {?number} */

    let index = this.getLISTINFOIndex_();

    /** @type {!Object} */

    let tags = {};

    if (index !== null) {

      for (let i=0; i<this.LIST[index].subChunks.length; i++) {

        tags[this.LIST[index].subChunks[i].chunkId] =

          this.LIST[index].subChunks[i].value;

      }

    }

    return tags;

  }

  /**

   * Remove a RIFF tag in the INFO chunk.

   * @param {string} tag The tag name.

   * @return {boolean} True if a tag was deleted.

   */

  deleteTag(tag) {

    /** @type {!Object} */

    let index = this.getTagIndex_(tag);

    if (index.TAG !== null) {

      this.LIST[index.LIST].subChunks.splice(index.TAG, 1);

      return true;

    }

    return false;

  }

  /**

   * Create a cue point in the wave file.

   * @param {number} position The cue point position in milliseconds.

   * @param {string} labl The LIST adtl labl text of the marker. Optional.

   */

  /**

   * Remove a cue point from a wave file.

   * @param {number} index the index of the point. First is 1,

   *    second is 2, and so on.

   */

  deleteCuePoint(index) {

    this.cue.chunkId = 'cue ';

    /** @type {!Array<!Object>} */

    let existingPoints = this.getCuePoints_();

    this.clearLISTadtl_();

    /** @type {number} */

    let len = this.cue.points.length;

    this.cue.points = [];

    for (let i=0; i<len; i++) {

      if (i + 1 !== index) {

        this.setCuePoint_(

          existingPoints[i].dwPosition,

          i + 1,

          existingPoints[i].label);

      }

    }

    this.cue.dwCuePoints = this.cue.points.length;

    if (this.cue.dwCuePoints) {

      this.cue.chunkId = 'cue ';

    } else {

      this.cue.chunkId = '';

      this.clearLISTadtl_();

    }

  }

  /**

   * Return an array with all cue points in the file, in the order they appear

   * in the file.

   * The difference between this method and using the list in WaveFile.cue

   * is that the return value of this method includes the position in

   * milliseconds of each cue point (WaveFile.cue only have the sample offset)

   * @return {!Array<!Object>}

   * @private

   */

  listCuePoints() {

    /** @type {!Array<!Object>} */

    let points = this.getCuePoints_();

    for (let i=0; i<points.length; i++) {

      points[i].milliseconds =

        (points[i].dwPosition / this.fmt.sampleRate) * 1000;

    }

    return points;

  }

  /**

   * Update the label of a cue point.

   * @param {number} pointIndex The ID of the cue point.

   * @param {string} label The new text for the label.

   */

  updateLabel(pointIndex, label) {

    /** @type {?number} */

    let adtlIndex = this.getAdtlChunk_();

    if (adtlIndex !== null) {

      for (let i=0; i<this.LIST[adtlIndex].subChunks.length; i++) {

        if (this.LIST[adtlIndex].subChunks[i].dwName ==

            pointIndex) {

          this.LIST[adtlIndex].subChunks[i].value = label;

        }

      }

    }

  }

  /**

   * Set the string code of the bit depth based on the 'fmt ' chunk.

   * @private

   */

  bitDepthFromFmt_() {

    if (this.fmt.audioFormat === 3 && this.fmt.bitsPerSample === 32) {

      this.bitDepth = '32f';

    } else if (this.fmt.audioFormat === 6) {

      this.bitDepth = '8a';

    } else if (this.fmt.audioFormat === 7) {

      this.bitDepth = '8m';

    } else {

      this.bitDepth = this.fmt.bitsPerSample.toString();

    }

  }

  /**

   * Push a new cue point in this.cue.points.

   * @param {number} position The position in milliseconds.

   * @param {number} dwName the dwName of the cue point

   * @private

   */

  setCuePoint_(position, dwName, label) {

    this.cue.points.push({

      dwName: dwName,

      dwPosition: position,

      fccChunk: 'data',

      dwChunkStart: 0,

      dwBlockStart: 0,

      dwSampleOffset: position,

    });

    this.setLabl_(dwName, label);

  }

  /**

   * Return an array with all cue points in the file, in the order they appear

   * in the file.

   * @return {!Array<!Object>}

   * @private

   */

  getCuePoints_() {

    /** @type {!Array<!Object>} */

    let points = [];

    for (let i=0; i<this.cue.points.length; i++) {

      points.push({

        dwPosition: this.cue.points[i].dwPosition,

        label: this.getLabelForCuePoint_(

          this.cue.points[i].dwName)});

    }

    return points;

  }

  /**

   * Return the label of a cue point.

   * @param {number} pointDwName The ID of the cue point.

   * @return {string}

   * @private

   */

  getLabelForCuePoint_(pointDwName) {

    /** @type {?number} */

    let adtlIndex = this.getAdtlChunk_();

    if (adtlIndex !== null) {

      for (let i=0; i<this.LIST[adtlIndex].subChunks.length; i++) {

        if (this.LIST[adtlIndex].subChunks[i].dwName ==

            pointDwName) {

          return this.LIST[adtlIndex].subChunks[i].value;

        }

      }

    }

    return '';

  }

  /**

   * Clear any LIST chunk labeled as 'adtl'.

   * @private

   */

  clearLISTadtl_() {

    for (let i=0; i<this.LIST.length; i++) {

      if (this.LIST[i].format == 'adtl') {

        this.LIST.splice(i);

      }

    }

  }

  /**

   * Create a new 'labl' subchunk in a 'LIST' chunk of type 'adtl'.

   * @param {number} dwName The ID of the cue point.

   * @param {string} label The label for the cue point.

   * @private

   */

  setLabl_(dwName, label) {

    /** @type {?number} */

    let adtlIndex = this.getAdtlChunk_();

    if (adtlIndex === null) {

      this.LIST.push({

        chunkId: 'LIST',

        chunkSize: 4,

        format: 'adtl',

        subChunks: []});

      adtlIndex = this.LIST.length - 1;

    }

    this.setLabelText_(adtlIndex === null ? 0 : adtlIndex, dwName, label);

  }

  /**

   * Create a new 'labl' subchunk in a 'LIST' chunk of type 'adtl'.

   * @param {number} adtlIndex The index of the 'adtl' LIST in this.LIST.

   * @param {number} dwName The ID of the cue point.

   * @param {string} label The label for the cue point.

   * @private

   */

  setLabelText_(adtlIndex, dwName, label) {

    this.LIST[adtlIndex].subChunks.push({

      chunkId: 'labl',

      chunkSize: label.length,

      dwName: dwName,

      value: label

    });

    this.LIST[adtlIndex].chunkSize += label.length + 4 + 4 + 4 + 1;

  }

  /**

   * Return the index of the 'adtl' LIST in this.LIST.

   * @return {?number}

   * @private

   */

  getAdtlChunk_() {

    for (let i=0; i<this.LIST.length; i++) {

      if (this.LIST[i].format == 'adtl') {

        return i;

      }

    }

    return null;

  }

  /**

   * Return the index of the INFO chunk in the LIST chunk.

   * @return {?number} the index of the INFO chunk.

   * @private

   */

  getLISTINFOIndex_() {

    /** @type {?number} */

    let index = null;

    for (let i=0; i<this.LIST.length; i++) {

      if (this.LIST[i].format === 'INFO') {

        index = i;

        break;

      }

    }

    return index;

  }

  /**

   * Return the index of a tag in a FILE chunk.

   * @param {string} tag The tag name.

   * @return {!Object<string, ?number>}

   *    Object.LIST is the INFO index in LIST

   *    Object.TAG is the tag index in the INFO

   * @private

   */

  getTagIndex_(tag) {

    /** @type {!Object<string, ?number>} */

    let index = {LIST: null, TAG: null};

    for (let i=0; i<this.LIST.length; i++) {

      if (this.LIST[i].format == 'INFO') {

        index.LIST = i;

        for (let j=0; j<this.LIST[i].subChunks.length; j++) {

          if (this.LIST[i].subChunks[j].chunkId == tag) {

            index.TAG = j;

            break;

          }

        }

        break;

      }

    }

    return index;

  }

  /**

   * Fix a RIFF tag format if possible, throw an error otherwise.

   * @param {string} tag The tag name.

   * @return {string} The tag name in proper fourCC format.

   * @private

   */

  fixTagName_(tag) {

    if (tag.constructor !== String) {

      throw new Error('Invalid tag name.');

    } else if (tag.length < 4) {

      for (let i=0; i<4-tag.length; i++) {

        tag += ' ';

      }

    }

    return tag;

  }

  /**

   * Reset attributes that should emptied when a file is

   * created with the fromScratch() or fromBuffer() methods.

   * @private

   */

  clearHeader_() {

    this.fmt.cbSize = 0;

    this.fmt.validBitsPerSample = 0;

    this.fact.chunkId = '';

    this.ds64.chunkId = '';

  }

  /**

   * Make the file 16-bit if it is not.

   * @private

   */

  assure16Bit_() {

    this.assureUncompressed_();

    if (this.bitDepth != '16') {

      this.toBitDepth('16');

    }

  }

  /**

   * Uncompress the samples in case of a compressed file.

   * @private

   */

  assureUncompressed_() {

    if (this.bitDepth == '8a') {

      this.fromALaw();

    } else if (this.bitDepth == '8m') {

      this.fromMuLaw();

    } else if (this.bitDepth == '4') {

      this.fromIMAADPCM();

    }

  }

  /**

   * Set up the WaveFile object from a byte buffer.

   * @param {!Array<number>|!Array<!Array<number>>|!ArrayBufferView} samples The samples.

   * @private

   */

  interleave_(samples) {

    if (samples.length > 0) {

      if (samples[0].constructor === Array) {

        /** @type {!Array<number>} */

        let finalSamples = [];

        for (let i=0; i < samples[0].length; i++) {

          for (let j=0; j < samples.length; j++) {

            finalSamples.push(samples[j][i]);

          }

        }

        samples = finalSamples;

      }

    }

    return samples;

  }

  /**

   * Update the type definition used to read and write the samples.

   * @private

   */

  updateDataType_() {

    /** @type {!Object} */

    this.dataType = {

      bits: ((parseInt(this.bitDepth, 10) - 1) | 7) + 1,

      float: this.bitDepth == '32f' || this.bitDepth == '64',

      signed: this.bitDepth != '8',

      be: this.container == 'RIFX'

    };

    if (['4', '8a', '8m'].indexOf(this.bitDepth) > -1 ) {

      this.dataType.bits = 8;

      this.dataType.signed = false;

    }

  }

  /**

   * Return 'RIFF' if the container is 'RF64', the current container name

   * otherwise. Used to enforce 'RIFF' when RF64 is not allowed.

   * @return {string}

   * @private

   */

  correctContainer_() {

    return this.container == 'RF64' ? 'RIFF' : this.container;

  }

}